home *** CD-ROM | disk | FTP | other *** search
/ The Very Best of Atari Inside / The Very Best of Atari Inside 1.iso / mint / mnthlp95 / source / f.src < prev    next >
Text File  |  1992-08-04  |  35KB  |  1,061 lines
  1. screen(capsensitive("Fchmod"))
  2. NAME
  3.     Fchmod - set file access permissions
  4.  
  5. SYNOPSIS
  6.     #include <filesys.h>
  7.  
  8.     LONG Fchmod(char *name, WORD mode);
  9.  
  10. DESCRIPTION
  11.     Fchmod changes the file access  permissions for the file
  12.     named name. The new access permissions are given in the
  13.     word mode, which may be constructed by or'ing together the
  14.     following symbolic constants (defined in filesys.h):
  15.  
  16.     S_IRUSR,
  17.         Read, write, and execute permission (respectively) for
  18.         the owner of the file.
  19.  
  20.     S_IRGRP,
  21.         Read, write, and execute permission (respectively) for
  22.         the file's group.
  23.  
  24.     S_IROTH,
  25.         Read, write, and execute permission for everybody else.
  26.  
  27.     Note that not all file systems support all of these bits;
  28.     bits not supported by a file system will be ignored.
  29.  
  30.     Note also that "execute" permission for a directory means
  31.     permission to search the directory for a file name or name
  32.     component.
  33.  
  34. RETURNS
  35.     0 on success
  36.  
  37.     EACCDN if the calling process has an effective uid which
  38.     differs from the owner of the file and which is not 0.
  39.  
  40.     EFILNF if the file is not found
  41.  
  42.     EPTHNF if the path to the file is not found.
  43.  
  44. SEE ALSO
  45.     \#Fattrib\#, \#Fxattr\#
  46.  
  47. Last change: Oct. 7, 1991\end
  48.  
  49. screen(capsensitive("Fchown"))
  50. NAME
  51.     Fchown - change a file's ownership
  52.  
  53. SYNOPSIS
  54.     LONG Fchown(char *name, WORD uid, WORD gid);
  55.  
  56. DESCRIPTION
  57.     Fchown changes a file's user and group ownership to uid and
  58.     gid respectively. These ownerships determine access rights
  59.     to the file.
  60.  
  61.     Only a process with effective uid 0 or whose effective uid
  62.     matches the user ownership of the file may make this call.
  63.     In the latter case, the new uid must match the old one, and
  64.     the calling process must also be a member of the group
  65.     specified by gid.
  66.  
  67. RETURNS
  68.     0 on success
  69.  
  70.     EACCDN if the calling process has an effective uid which
  71.     differs from the owner of the file and which is not 0.
  72.  
  73.     EINVFN if the file system on which the file is located does
  74.     not support a notion of ownership. (This is true of the nor-
  75.     mal TOS file system.)
  76.  
  77.     EFILNF if the file is not found
  78.  
  79.     EPTHNF if the path to the file is not found.
  80.  
  81. SEE ALSO
  82.     \#Fchmod\#, \#Fxattr\#
  83.  
  84. BUGS
  85.     Most file systems don't understand file ownership.
  86.  
  87.     In practice, the call is useful only to processes with
  88.     effective uid 0.
  89.  
  90. Last change: Dec. 12, 1991\end
  91.  
  92. screen(capsensitive("Fcntl"))
  93. NAME
  94.     Fcntl - perform various control operations on a file
  95.  
  96. SYNOPSIS
  97.     #include <filesys.h>
  98.  
  99.     LONG Fcntl(WORD fh, LONG arg, WORD cmd);
  100.  
  101. DESCRIPTION
  102.     Fcntl performs various control operations on the open file
  103.     with GEMDOS file handle fh. The specific command to perform
  104.     is given by cmd; the possible commands are given by symbolic
  105.     constants in filesys.h, and are listed below. arg is an
  106.     argument whose meaning depends on the command.
  107.  
  108.     The following commands are applicable to any file descriptor:
  109.  
  110.     \link("Fcntl file commands")F_DUPFD\#
  111.  
  112.     \link("Fcntl file commands")F_GETFD\#
  113.  
  114.     \link("Fcntl file commands")F_SETFD\#
  115.  
  116.     \link("Fcntl file commands")F_GETFL\#
  117.  
  118.     \link("Fcntl file commands")F_SETFL\#
  119.  
  120.     \link("Fcntl file commands")F_GETLK\#
  121.  
  122.     \link("Fcntl file commands")F_SETLK\#
  123.     
  124.     \link("Fcntl file commands")FSTAT\#
  125.  
  126.     \link("Fcntl file commands")FIONREAD\#
  127.  
  128.     \link("Fcntl file commands")FIONWRITE\#
  129.  
  130.     The following commands are valid for any terminal device,
  131.     e.g. the console or a pseudo-terminal:
  132.  
  133.     \link("Fcntl terminal commands")TIOCGETP\#
  134.  
  135.     \link("Fcntl terminal commands")TIOCSETP\#
  136.  
  137.     \link("Fcntl terminal commands")TIOCGETC\#
  138.  
  139.     \link("Fcntl terminal commands")TIOCSETC\#
  140.  
  141.     \link("Fcntl terminal commands")TIOCGLTC\#
  142.  
  143.     \link("Fcntl terminal commands")TIOCSLTC\#
  144.  
  145.     \link("Fcntl terminal commands")TIOCGWINSZ\#
  146.  
  147.     \link("Fcntl terminal commands")TIOCSWINSZ\#
  148.  
  149.     \link("Fcntl terminal commands")TIOCGPGRP\#
  150.  
  151.     \link("Fcntl terminal commands")TIOCSPGRP\#
  152.  
  153.     \link("Fcntl terminal commands")TIOCSTART\#
  154.  
  155.     \link("Fcntl terminal commands")TIOCSTOP\#
  156.  
  157.     \link("Fcntl terminal commands")TIOCGXKEY\#
  158.  
  159.     \link("Fcntl terminal commands")TIOCSXKEY\#
  160.  
  161.     The following commands are valid only for processes opened
  162.     as files:
  163.  
  164.     \link("Fcntl process commands")PBASEADDR\#
  165.  
  166.     \link("Fcntl process commands")PPROCADDR\#
  167.  
  168.     \link("Fcntl process commands")PCTXTSIZE\#
  169.     
  170.     The following commands are valid only for files which
  171.     represent shared memory:
  172.  
  173.     \link("Fcntl shared memory commands")SHMSETBLK\#
  174.     
  175.     \link("Fcntl shared memory commands")SHMGETBLK\#
  176.     
  177. RETURNS
  178.     0 or a positive number if successful (for most commands, 0,
  179.     but see the specific descriptions above).
  180.  
  181.     EIHNDL if fh is not a valid GEMDOS open handle.
  182.  
  183.     EINVFN if the specified command is not valid for this file
  184.     handle.
  185.  
  186.     Some other (LONG) negative error number if an error occurs;
  187.     different commands may recognize different possible errors.
  188.  
  189. SEE ALSO
  190.     \#Fdup\#, \#Flock\#, \#Fopen\#, \#Fxattr\#, \#Pgetpgrp\#, \#Psetpgrp\#
  191.  
  192. BUGS
  193.     Very little error checking is done. In particular, ownership
  194.     of terminals is not properly checked, nor is read/write
  195.     access to the files. Do not rely on this bug; it will be
  196.     fixed some day.
  197.  
  198.     File locking is not yet implemented for most file systems.
  199.  
  200.     Very few of the terminal control options have effect on ter-
  201.     minals connected via serial ports or midi. In particular, it
  202.     is not possible to set the baud rate, parity, flow control,
  203.     or similar options with Fcntl. However, this bug will be
  204.     fixed in future versions of the operating system, so pro-
  205.     grams should never modify the sg_ispeed, sg_ospeed, or
  206.     sg_flags fields of the \#sgttyb\# structure, and should always
  207.     use TIOCGETP to obtain the original settings of these fields
  208.     before calling TIOCSETP.
  209.  
  210. Last change: July 20, 1992\end
  211.  
  212. screen("Fcntl file commands")
  213. The following \#Fcntl\# commands are applicable to any file descriptor:
  214.  
  215. F_DUPFD
  216.     Return a duplicate for the file handle. The new (dupli-
  217.     cate) handle will be an integer >= arg and < 32. If no
  218.     free handles exist in that range, ENHNDL will be
  219.     returned. The \#Fdup\# system call is equivalent to
  220.     Fcntl(fh, 6L, F_DUPFD)
  221.  
  222. F_GETFD
  223.     Return the noinherit flag for the file descriptor. This
  224.     flag is 1 if child processes started by Pexec should
  225.     inherit this open file, and 0 if not. arg is ignored.
  226.  
  227. F_SETFD
  228.     Set the noinherit flag for the file descriptor from the
  229.     low order bit of arg. The default value of the flag is
  230.     0 for handles 0-5 (the "standard" handles) and 1 for
  231.     other (non-standard) handles. Note that the noinherit
  232.     flag applies only to this particular file descriptor;
  233.     another descriptor obtained from fh by the \#Fdup\# system
  234.     call or by use of the F_DUPFD option to \#Fcntl\# will have
  235.     the noinherit flag set to the default. Also note that
  236.     these defaults are not the same as for the Unix operat-
  237.     ing system.
  238.  
  239. F_GETFL
  240.     Returns the user-settable file descriptor flags. These
  241.     flags are the same as the mode passed to \#Fopen\#, unless
  242.     they have been further modified by another \#Fcntl\# opera-
  243.     tion. arg is ignored.
  244.  
  245. F_SETFL
  246.     Set user-settable file descriptor flags from the argu-
  247.     ment arg. Only the user-settable bits in arg are con-
  248.     sidered; the settings of other bits are ignored, but
  249.     should be 0 for future compatibility. Moreover, it is
  250.     not possible to change a file's read-write mode or
  251.     sharing modes with this call; attempts to do so will
  252.     (silently) fail.
  253.  
  254. F_GETLK
  255.     arg is a pointer to an \#flock\# structure.
  256.     If a lock exists which would prevent this lock from
  257.     being applied to the file, the existing lock is copied
  258.     into the structure and the l_pid field is set to the
  259.     process id of the locking process. Otherwise, l_type is
  260.     set to F_UNLCK. If a conflicting lock is held by a pro-
  261.     cess on a different machine on a network, then the
  262.     l_pid field will be set to a value defined by the net-
  263.     work file system. This value will be in the range
  264.     0x1000 to 0xFFFF, and will therefore not conflict with
  265.     any process id since process id's must be less than
  266.     0x1000.
  267.  
  268. F_SETLK
  269.     Set (if l_type is F_RDLCK or F_WRLCK) or clear (if
  270.     l_type is F_UNLCK) an advisory lock on a file. If the
  271.     file is a FIFO, the whole file must be locked or
  272.     unlocked at once, i.e. l_whence, l_start, and l_len
  273.     must be 0. If this lock would conflict with a lock held
  274.     by another process, ELOCKED is returned. If an attempt
  275.     is made to clear a non-existent lock, ENSLOCK is
  276.     returned. More than one read lock may be placed on the
  277.     same region of a file, but no write lock may overlap
  278.     with any other sort of lock. If a process holds locks
  279.     on a file, then the locks are automatically released
  280.     whenever the process closes an open file handle refer-
  281.     ring to that file, or when the process terminates.
  282.     
  283. FSTAT
  284.     arg points to an XATTR structure, which is filled in
  285.     with the appropriate extended file attributes for
  286.     the file to which fd refers just as though the \#Fxattr\#
  287.     system call had been made on the file.
  288.  
  289. FIONREAD
  290.     arg points to a 32 bit integer, into which is written
  291.     the number of bytes that are currently available to be
  292.     read from this descriptor; a read of this number of
  293.     bytes or less should not cause the process to block
  294.     (wait for more input). Note that for some files only
  295.     an estimate can be provided, so the number is not
  296.     always completely accurate.
  297.  
  298. FIONWRITE
  299.     arg points to a 32 bit integer, into which is written
  300.     the number of bytes that may be written to the indi-
  301.     cated file descriptor without causing the process to
  302.     block. Note that for some files only an estimate can
  303.     be provided, so the number is not always completely
  304.     accurate.
  305.         
  306. Last change: July 20, 1992\end
  307.  
  308. screen("flock")
  309. The file lock structure is used in a \link("Fcntl file commands")F_GETLK\# or \link("Fcntl file commands")F_SETLK\#
  310. command in a \#Fcntl\# call.
  311.  
  312. The flock structure is defined in FILESYS.H:
  313.  
  314. struct flock 
  315. {
  316.     short   l_type;     /* type of lock                   */
  317.     #define F_RDLCK 0
  318.     #define F_WRLCK 1
  319.     #define F_UNLCK 3
  320.     short   l_whence;   /* 0:file start, 1:current, 2:EOF */
  321.     long    l_start;    /* offset of locked region        */
  322.     long    l_len;      /* 0 for rest of file             */
  323.     short   l_pid;      /* set by F_GETLK                 */
  324. };\end
  325.  
  326. screen("Fcntl terminal commands")
  327. The following \#Fcntl\# commands are valid for any terminal device,
  328. e.g. the console or a pseudo-terminal:
  329.  
  330. TIOCGETP
  331.     Get terminal parameters from the \link("sgttyb")terminal description\# 
  332.     structure pointed to by arg.
  333.  
  334. TIOCSETP
  335.     Set terminal parameters from the struct \#sgttyb\# pointed
  336.     to by arg.
  337.  
  338. TIOCGETC
  339.     Get terminal control characters. arg is a pointer to
  340.     a \link("tchars")terminal control\# structure.
  341.  
  342. TIOCSETC
  343.     Set terminal control characters from the struct \#tchars\#
  344.     pointed to by arg. Setting any character to the value
  345.     0 causes the corresponding function to become unavail-
  346.     able.
  347.  
  348. TIOCGLTC
  349.     Get extended terminal control characters, and put them
  350.     in the \#ltchars\# structure pointed to by arg.
  351.  
  352. TIOCSLTC
  353.     Set extended terminal control characters from the
  354.     struct \#ltchars\# pointed to by arg. Setting any of the
  355.     characters to 0 causes the corresponding function to
  356.     become unavailable.
  357.  
  358. TIOCGWINSZ
  359.     arg has type \link("winsize")struct winsize *\#. The current window
  360.     size for this window is placed in the structure pointed
  361.     to by arg.
  362.  
  363. TIOCSWINSZ
  364.     arg has type \link("winsize")struct winsize *\#. The current window
  365.     size for the window is set from the structure pointed
  366.     to by arg. Note that the kernel maintains the informa-
  367.     tion but does not act upon it in any way; it is up to
  368.     window managers to perform whatever physical changes
  369.     are necessary to alter the window size, and to raise
  370.     the SIGWINCH signal if necessary.
  371.  
  372. TIOCGPGRP
  373.     arg has type "long *"; the process group for the termi-
  374.     nal is placed into the long pointed to by it.
  375.  
  376. TIOCSPGRP
  377.     arg has type "long *"; the process group for the termi-
  378.     nal is set from the long pointed to by it. Processes in
  379.     any other process group will be sent job control sig-
  380.     nals if they attempt input or output to the terminal.
  381.  
  382. TIOCSTART
  383.     Restart output to the terminal (as though the user
  384.     typed control-Q) if it was stopped by a control-S or
  385.     TIOCSTOP command. arg is ignored.
  386.  
  387. TIOCSTOP
  388.     Stop output to the terminal (as though the user typed
  389.     control-S). arg is ignored.
  390.  
  391. TIOCGXKEY
  392.     Get the definition of a function or cursor key. arg is
  393.     a pointer to an \#xkey\# structure.
  394.  
  395. TIOCSXKEY
  396.     arg is a structure of type \link("xkey")struct xkey\#, as defined
  397.     above. Both the xk_num and the xk_def fields must be
  398.     defined. After execution of this command, and if the
  399.     XKEY bit is set in the sg_flags field of the \#sgttyb\#
  400.     structure associated with the terminal, then if the
  401.     indicated key is pressed on the affected terminal, any
  402.     MiNT domain process using \#Fread\# to read the key will
  403.     get the string in xk_def instead of ASCII 0. Note that
  404.     this translation occurs only for MiNT domain processes
  405.     and only for the \#Fread\# system call. Also note that the
  406.     string in xk_def must be null terminated, and so at
  407.     most 7 characters may be assigned to any key.
  408.         
  409. Last change: July 20, 1992\end
  410.  
  411. screen("sgttyb")
  412. The terminal description structure is used in a \link("Fcntl terminal commands")TIOCGETP\#
  413. or \link("Fcntl terminal commands")TIOCSETP\# command in a \#Fcntl\# call.
  414.  
  415. The sgttyb structure is defined in FILESYS.H:
  416.  
  417. struct sgttyb
  418. {
  419.     char    sg_ispeed;  /* reserved               */
  420.     char    sg_ospeed;  /* reserved               */
  421.     char    sg_erase;   /* erase character        */
  422.     char    sg_kill;    /* line kill character    */
  423.     short   sg_flags;   /* terminal control flags */
  424. };\end
  425.  
  426. screen("tchars")
  427. The terminal control structure is used in a \link("Fcntl terminal commands")TIOCGETC\#
  428. or \link("Fcntl terminal commands")TIOCSETC\# command in a \#Fcntl\# call.
  429.  
  430. The tchars structure is defined in FILESYS.H:
  431.  
  432. struct tchars
  433. {
  434.     char    t_intrc;    /* raises SIGINT          */
  435.     char    t_quitc;    /* raises SIGQUIT         */
  436.     char    t_startc;   /* starts terminal output */
  437.     char    t_stopc;    /* stops terminal output  */
  438.     char    t_eofc;     /* marks end of file      */
  439.     char    t_brkc;     /* marks end of line      */
  440. };\end
  441.  
  442. screen("ltchars")
  443. The extended terminal control structure is used in a 
  444. \link("Fcntl terminal commands")TIOCGLTC\# or \link("Fcntl terminal commands")TIOCSLTC\# command in a \#Fcntl\# call.
  445.  
  446. The ltchars structure is defined in FILESYS.H:
  447.  
  448. struct ltchars
  449. {
  450.     char    t_suspc;    /* raises SIGTSTP now       */
  451.     char    t_dsuspc;   /* raises SIGTSTP when read */
  452.     char    t_rprntc;   /* redraws the input line   */
  453.     char    t_flushc;   /* flushes output           */
  454.     char    t_werasc;   /* erases a word            */
  455.     char    t_lnextc;   /* quotes a character       */
  456. };\end
  457.  
  458. screen("winsize")
  459. The window size structure is used in a \link("Fcntl terminal commands")TIOCGWINSZ\#
  460. or \link("Fcntl terminal commands")TIOCSWINSZ\# command in a \#Fcntl\# call.
  461.  
  462. The winsize structure is defined in FILESYS.H:
  463.  
  464. struct winsize
  465. {
  466.     short   ws_row;     /* # of rows of text in window */
  467.     short   ws_col;     /* # of columns of text        */
  468.     short   ws_xpixel;  /* width of window in pixels   */
  469.     short   ws_ypixel;  /* height of window in pixels  */
  470. };
  471.  
  472. If any fields in the structure are 0, this means that
  473. the corresponding value is unknown.\end
  474.  
  475. screen("xkey")
  476. The key definition structure is used in a \link("Fcntl terminal commands")TIOCGXKEY\#
  477. or \link("Fcntl terminal commands")TIOCSXKEY\# command in a \#Fcntl\# call.
  478.  
  479. The xkey structure is defined in FILESYS.H:
  480.  
  481. struct xkey
  482. {
  483.     short   xk_num;    /* function key number */
  484.     char    xk_def[8]; /* associated string   */
  485. };
  486.     
  487. The xk_num field must be initialized with the number of
  488. the desired key:
  489.  
  490. xk_num      Key
  491.    0-9      F1-F10
  492.  10-19      F11-F20 (shift F1-shift F10)
  493.     20      cursor up
  494.     21      cursor down
  495.     22      cursor right
  496.     23      cursor left
  497.     24      help
  498.     25      undo
  499.     26      insert
  500.     27      clr/home
  501.     28      shift+cursor up
  502.     29      shift+cursor down
  503.     30      shift+cursor right
  504.     31      shift+cursor left
  505.  
  506. The string currently associated with the indicated key
  507. is copied into xk_def; this string is always nullterminated.\end
  508.     
  509. screen("Fcntl process commands")
  510. The following \#Fcntl\# commands are valid only for processes opened
  511. as files:
  512.  
  513. PBASEADDR
  514.     arg is a pointer to a 32 bit integer, into which the
  515.     address of the process basepage for the process to
  516.     which fh refers is written.
  517.  
  518. PPROCADDR
  519.     arg is a pointer to a 32 bit integer, into which the
  520.     address of the process control structure for the pro-
  521.     cess is written. Note that this control structure
  522.     differs from the one found in previous versions (before
  523.     0.93) of MiNT; it no longer includes the process con-
  524.     text, so that this part of the structure may be changed
  525.     without causing compatibility problems. See the
  526.     PCTXTSIZE command.
  527.  
  528. PCTXTSIZE
  529.     arg is a pointer to a 32 bit integer, into which the
  530.     length of a process context structure is written. There
  531.     are two of these structures located in memory just
  532.     before the process control structure whose address is
  533.     returned by the PPROCADDR command. The first is the
  534.     current process context; the second is the saved con-
  535.     text from the last system call.
  536.  
  537. Last change: July 20, 1992\end
  538.  
  539. screen(capsensitive("Fcntl shared memory commands"))
  540. The following \#Fcntl\# commands are valid only for files which
  541. represent shared memory:
  542.  
  543. SHMSETBLK
  544.     arg is a pointer to a block of memory previously allocated
  545.     by \#Mxalloc\#. The memory will be offered for sharing
  546.     under the name of the file represented by fd (which
  547.     must be a file in the U:\\SHM directory).
  548.   
  549. SHMGETBLK
  550.     arg must be 0, for future compatibility. Returns the
  551.     address of the block of memory previously associated
  552.     with the file via SHMSETBLK, or a NULL pointer if an
  553.     error occurs. Note that different processes may see
  554.     the shared memory block at different addresses in their
  555.     address spaces. Therefore, the shared memory block
  556.     should not contain any absolute pointers to data.
  557.   
  558. Last change: July 20, 1992\end
  559. screen(capsensitive("Fgetchar"))
  560. NAME
  561.     Fgetchar - read a character from a file
  562.  
  563. SYNOPSIS
  564.     LONG Fgetchar(WORD fh, WORD mode);
  565.  
  566. DESCRIPTION
  567.     Fgetchar reads a character from the open file whose handle
  568.     is fh. The parameter mode has an effect only if the open
  569.     file is a terminal or pseudo-terminal, in which case the
  570.     bits of mode have the following meanings:
  571.  
  572.     0x0001
  573.         Cooked mode; special control characters (control-C and
  574.         control-Z) are checked for and interpreted if found
  575.         (they cause SIGINT and SIGTSTP, respectively, to be
  576.         raised); also, flow control with control-S and
  577.         control-Q is activated.
  578.  
  579.     0x0002
  580.         Echo mode; characters read are echoed back to the ter-
  581.         minal.
  582.  
  583.     The ASCII value of the character read is put in the low byte
  584.     of the long word that is returned. If the file is a terminal
  585.     or pseudo-terminal, the scan code of the character pressed
  586.     and (possibly) the shift key status are also returned in the
  587.     long word, just as with the BIOS \#Bconin\# system call.
  588.  
  589. RETURNS
  590.     The character read, if successful.
  591.  
  592.     0x0000FF1A if end of file is detected.
  593.  
  594.     EIHNDL if fh is not a valid handle for an open file.
  595.  
  596. SEE ALSO
  597.     \#Bconin\#, \#Cconin\#, \#Cauxin\#, \#Fputchar\#, \#Fread\#
  598.  
  599. Last change: Oct. 1, 1991\end
  600.  
  601. screen(capsensitive("Finstat"))
  602. NAME
  603.     Finstat - determine input status for a file
  604.  
  605. SYNOPSIS
  606.     LONG Finstat(WORD fh);
  607.  
  608. DESCRIPTION
  609.     Finstat returns the number of bytes of input waiting on the
  610.     file whose GEMDOS handle is fh, or 0 if no input is avail-
  611.     able on that handle.
  612.  
  613. RETURNS
  614.     0 or a positive number if successful
  615.  
  616.     EIHNDL if fh is not a valid handle for an open file.
  617.  
  618. SEE ALSO
  619.     \#Cauxis\#, \#Cconis\#, \#Fcntl\#, \#Foutstat\#
  620.  
  621. BUGS
  622.     Always returns 1 for disk files.
  623.  
  624.     Doesn't check to see if the indicated file was opened for
  625.     reading.
  626.  
  627. Last change: Oct. 1, 1991\end
  628.  
  629. screen(capsensitive("Flink"))
  630. NAME
  631.     Flink - create a new link to a file
  632.  
  633. SYNOPSIS
  634.     LONG Flink(char *oldname, char *newname);
  635.  
  636. DESCRIPTION
  637.     Flink creates a new name (a "hard link") for the file
  638.     currently named oldname. If the Flink call is successful,
  639.     then after the call the file may be referred to by either
  640.     name, and a call to \#Fdelete\# on either name will not affect
  641.     access to the file through the other name. oldname and
  642.     newname must both refer to files on the same physical dev-
  643.     ice. Note also that not all file systems allow links.
  644.  
  645. RETURNS
  646.     0 on success
  647.  
  648.     EXDEV if oldname and newname refer to files on different
  649.     physical devices
  650.  
  651.     EINVFN if the file system does not allow hard links
  652.  
  653.     EFILNF if the file named oldname does not currently exist
  654.  
  655. SEE ALSO
  656.     \#Frename\#, \#Fsymlink\#
  657.     
  658. Last change: Oct. 7, 1991\end
  659.  
  660. screen(capsensitive("Fmidipipe"))
  661. NAME
  662.     Fmidipipe - redirect MIDI input and output
  663.  
  664. SYNOPSIS
  665.     LONG Fmidipipe(WORD pid, WORD in, WORD out);
  666.  
  667. DESCRIPTION
  668.     Fmidipipe changes the MIDI input and output file handles
  669.     (GEMDOS file handles -4 and -5 respectively) for process
  670.     pid. in is the GEMDOS handle (for the calling process) which
  671.     will become the MIDI input for the receiving process, and
  672.     out is the GEMDOS handle which is to become the MIDI output.
  673.  
  674.     If pid is 0, then the call affects the current process; in
  675.     this case, it is roughly equivalent to the sequence
  676.         Fforce(-4, in);
  677.         Fforce(-5, out);
  678.  
  679. RETURNS
  680.     0 on success
  681.  
  682.     EFILNF if the indicated process is not found
  683.  
  684.     EIHNDL if either in or out is not a valid open handle.
  685.  
  686.     EACCDN if in is not open for reading or if out is not open
  687.     for writing.
  688.  
  689. SEE ALSO
  690.     \#Fdup\#, \#Fforce\#
  691.  
  692. BUGS
  693.     Any user can change the MIDI input and output of any pro-
  694.     cess. This will eventually be corrected.
  695.  
  696. Last change: Oct. 1, 1991\end
  697.  
  698. screen(capsensitive("Foutstat"))
  699. NAME
  700.     Foutstat - determine output status for a file
  701.  
  702. SYNOPSIS
  703.     LONG Foutstat(WORD fh);
  704.  
  705. DESCRIPTION
  706.     Foutstat returns the number of bytes of output that may be
  707.     written to the file whose GEMDOS handle is fh, without
  708.     blocking.
  709.  
  710. RETURNS
  711.     0 or a positive number if successful
  712.  
  713.     EIHNDL if fh is not a valid handle for an open file.
  714.  
  715. SEE ALSO
  716.     \#Cauxos\#, \#Cconos\#, \#Cprnos\#, \#Fcntl\#, \#Finstat\#
  717.  
  718. BUGS
  719.     Always returns 1 for disk files.
  720.  
  721.     Doesn't check to see if the indicated file  was opened for
  722.     writing.
  723.  
  724. Last Change: Oct. 1, 1991\end
  725.  
  726. screen(capsensitive("Fpipe"))
  727. NAME
  728.     Fpipe - create a pipe
  729.  
  730. SYNOPSIS
  731.     LONG Fpipe(WORD usrh[2]);
  732.  
  733. DESCRIPTION
  734.     Fpipe creates a pipe that may be used for interprocess com-
  735.     munication. If it is successful, two GEMDOS handles are
  736.     returned in usrh[0] and usrh[1]. usrh[0] will contain a han-
  737.     dle for the read end of the pipe, (opened for reading only),
  738.     and usrh[1] will contain a handle for the write end of the
  739.     pipe (opened for writing only).
  740.  
  741.     The created pipe has the name "sys$pipe.xxx", where "xxx" is
  742.     a three digit integer.
  743.  
  744. USAGE
  745.     Typically used by shells; the shell redirects its standard
  746.     input (or standard output) to the read (or write) end of the
  747.     pipe using \#Fdup\# and \#Fforce\# before launching a child; the
  748.     child will then read from (or write to) the pipe by default.
  749.  
  750. RETURNS
  751.     0 if successful
  752.  
  753.     ENHNDL if there are not 2 free handles to allocate for the
  754.     pipe
  755.  
  756.     ENSMEM if there is not enough free memory to create the pipe
  757.  
  758.     EACCDN if too many pipes already exist in the system
  759.  
  760. BUGS
  761.     There cannot be more than 999 open pipes in the system at
  762.     one time.
  763.  
  764. Last change: Oct. 1, 1991\end
  765.  
  766. screen(capsensitive("Fputchar"))
  767. NAME
  768.     Fputchar - read a character from a file
  769.  
  770. SYNOPSIS
  771.     LONG Fputchar(WORD fh, LONG ch, WORD mode);
  772.  
  773. DESCRIPTION
  774.     Fputchar outputs a character to the GEMDOS file whose handle
  775.     is  fh. The parameter mode has an effect only if the open
  776.     file is a terminal or pseudo-terminal, in which case the
  777.     bits of mode have the following meanings:
  778.  
  779.     0x0001
  780.         Cooked mode; special control characters (control-C and
  781.         control-Z) are checked for  and interpreted if found
  782.         (they cause SIGINT and SIGTSTP, respectively, to be
  783.         raised); also, flow control with control-S and
  784.         control-Q is activated.
  785.  
  786.     If the file receiving output is a pseudo-terminal, then all
  787.     4 bytes of ch are recorded in the write, and may be
  788.     retreived by a Fputchar call on the other side of the
  789.     pseudo-terminal; this allows programs to pass simulated BIOS
  790.     scan codes and shift key status through the pseudo-terminal.
  791.  
  792.     If the file receiving output is not a terminal, then only
  793.     the low order byte of ch is written to the file.
  794.  
  795. RETURNS
  796.     4 (the number of bytes of data transferred) if the write was
  797.     to a terminal
  798.  
  799.     1 if the write was not to a terminal and was successful
  800.  
  801.     0 if the bytes could not be output (for example, because of
  802.     flow control)
  803.  
  804.     EIHNDL if fh is not a valid handle for an open file.
  805.  
  806.     A (long) negative BIOS error code if an error occured during
  807.     physical I/O.
  808.  
  809. SEE ALSO
  810.     \#Bconout\#, \#Cauxout\#, \#Cconout\#, \#Crawio\#, \#Fgetchar\#, \#Fwrite\#
  811.     
  812. Last change: Oct. 1, 1991\end
  813.  
  814. screen(capsensitive("Freadlink"))
  815. NAME
  816.     Freadlink - determine contents of a symbolic link
  817.  
  818. SYNOPSIS
  819.     LONG Freadlink(WORD bufsiz, char *buf, char *name);
  820.  
  821. DESCRIPTION
  822.     Freadlink determines what file the symbolic link name points
  823.     to, i.e. what the first argument to the \#Fsymlink\# call that
  824.     created name was. This 0-terminated string is placed in the
  825.     memory  region pointed to by buf. The total size of this
  826.     region is given by bufsiz; this must be enough to hold the
  827.     terminating 0.
  828.  
  829. RETURNS
  830.     0 on success
  831.  
  832.     ERANGE if the symbolic link contents could not fit in buf.
  833.  
  834.     EFILNF if name is not found.
  835.  
  836.     EACCDN if name is not the name of a symbolic link.
  837.  
  838.     EINVFN if the file system containing name does not support
  839.     symbolic links.
  840.  
  841. SEE ALSO
  842.     \#Fsymlink\#
  843.  
  844. BUGS
  845.     The Unix readlink call returns the number of bytes read on
  846.     success, rather than 0.
  847.  
  848. Last change: Oct. 7, 1992\end
  849.  
  850. screen(capsensitive("Fselect"))
  851. NAME
  852.     Fselect - select file descriptors that are ready for reading
  853.     or writing
  854.  
  855. SYNOPSIS
  856.     WORD Fselect(WORD timeout, LONG *rfds, LONG *wfds, ((long)0));
  857.  
  858. DESCRIPTION
  859.     Fselect checks two sets of open file descriptors and deter-
  860.     mines which have data ready to read, and/or which are ready
  861.     to be written to. If none are ready yet, the process goes to
  862.     sleep until some member of the sets are ready or until a
  863.     specified amount of time has elapsed.
  864.  
  865.     rfds points to a long word which represents a set of GEMDOS
  866.     file descriptors; bit n of this long word is set if file
  867.     descriptor n is to be checked for input data. An empty set
  868.     may optionally be represented by a NULL pointer instead of a
  869.     pointer to 0. Similarly, wfds points to a 32 bit long word
  870.     which indicates which file descriptors are to be checked for
  871.     output status. When Fselect returns, the old values pointed
  872.     to by rfds and wfds (if non-NULL) are overwritten by new
  873.     long words indicating which file descriptors are actually
  874.     ready for reading or writing; these will always form subsets
  875.     of the file descriptors originally  specified as being of
  876.     interest.
  877.  
  878.     timeout is a 16 bit unsigned integer specifying a maximum
  879.     number of milliseconds to wait before returning; if this
  880.     number is 0, no maximum is set and the call will block until
  881.     one of the file descriptors specified is ready for reading
  882.     or writing, as appropriate. Thus, Fselect(0,0L,0L,0L) will
  883.     block forever, whereas Fselect(1,0L,0L,0L) will pause for 1
  884.     millisecond.
  885.  
  886.     The final argument, a long word, must always be 0 (it is
  887.     reserved for future enhancements).
  888.  
  889. RETURNS
  890.     The sum of the numbers of bits set in the long words pointed
  891.     to  by rfds and wfds. This will be 0 if the timeout expires
  892.     without any of the specified file descriptors becoming ready
  893.     for reading or writing, as appropriate, and nonzero other-
  894.     wise.
  895.  
  896.     EIHNDL if any handle specified by the long words pointed to
  897.     by rfds or wfds is not a valid (open) GEMDOS handle.
  898.  
  899. SEE ALSO
  900.     \#Finstat\#, \#Foutstat\#
  901.  
  902. BUGS
  903.     The system timer is not actually accurate to the nearest
  904.     millisecond, so the timeout could last for up to 19 mil-
  905.     liseconds longer than specified.
  906.  
  907.     Fselect does not work correctly on any BIOS device except
  908.     the keyboard.
  909.  
  910.     Note that if an error condition occurs on one of the file
  911.     descriptors (for example, if the read status of a pipe with
  912.     no more writers is being requested) then Fselect will mark
  913.     that file descriptor as being ready for reading (or writing,
  914.     as appropriate). This is not strictly speaking a bug, since
  915.     a subsequent read will not block (it will return an error
  916.     condition), but programmers should be aware of the possibil-
  917.     ity.
  918.  
  919. Last change: Oct. 1, 1991\end
  920.  
  921. screen(capsensitive("Fsymlink"))
  922. NAME
  923.     Fsymlink - create a symbolic link to a file
  924.  
  925. SYNOPSIS
  926.     LONG Fsymlink(char *oldname, char *newname);
  927.  
  928. DESCRIPTION
  929.     Fsymlink creates a new symbolic link (a "soft link") for the
  930.     file currently named oldname. If the Fsymlink call is suc-
  931.     cessful, then after the call the file may be referred to by
  932.     either name. A call to \#Fdelete\# on the new name will not
  933.     affect the existence of the file, just of the symbolic link.
  934.     A a call to \#Fdelete\# with the name oldname will actually
  935.     delete the file, and future references with newname will
  936.     fail.
  937.  
  938.     Unlike hard links, symbolic links may be made between files
  939.     on  different devices or even different types of file systems.
  940.  
  941. RETURNS
  942.     0 on success
  943.  
  944.     EINVFN if the file system does not allow symbolic links
  945.  
  946.     An appropriate error code if the new symbolic link cannot be
  947.     created.
  948.  
  949. SEE ALSO
  950.     \#Flink\#, \#Freadlink\#, \#Frename\#
  951.  
  952. BUGS
  953.     No check is made for the existence of the file named old-
  954.     name; this could be construed as a feature.
  955.  
  956. Last change: Oct. 7, 1991\end
  957.  
  958. screen(capsensitive("Fxattr"))
  959. NAME
  960.     Fxattr - get extended attributes for a file
  961.  
  962. SYNOPSIS
  963.     #include <filesys.h>
  964.  
  965.     LONG Fxattr(WORD flag, char *name, XATTR *xattr);
  966.  
  967. DESCRIPTION
  968.     Fxattr gets file attributes for the file named name and
  969.     stores them in the structure pointed to by xattr. This
  970.     structure is defined in the file filesys.h, and contains the
  971.     following fields of interest:
  972.  
  973.     unsigned short mode
  974.         This field gives the file type and access permissions;
  975.         (mode & S_IFMT) gives the file type (one of S_IFCHR,
  976.         S_IFDIR, S_IFREG, S_IFIFO, S_IMEM, or S_IFLNK); (mode &
  977.         ~S_IFMT) gives the file access mode according to the
  978.         POSIX standard. See filesys.h for the definitions and
  979.         meanings of the constants.
  980.  
  981.     long index
  982.         An index for the file. Together with the "dev" field,
  983.         this is intended to give a unique way of identifying
  984.         the file. Note, however, that not all file systems  are
  985.         able to support this meaning, so it is best not to use
  986.         this field unless absolutely necessary.
  987.  
  988.     unsigned short dev
  989.         The device number for the file. This may be a BIOS device
  990.         number as passed to the \#Rwabs\# function, or it may be a
  991.         device number concocted by the file system to represent
  992.         a remote device.
  993.  
  994.     unsigned short nlink
  995.         Number of hard links to the file. Normally this field
  996.         will be 1.
  997.  
  998.     unsigned short uid
  999.         The user id of the owner of the file.
  1000.  
  1001.     unsigned short gid
  1002.         The group id of the owner of the file.
  1003.  
  1004.     long size
  1005.         The length of the file, in bytes.
  1006.  
  1007.     long blksize
  1008.         The size of blocks on this file system.
  1009.  
  1010.     long nblocks
  1011.         The number of physical blocks occupied by the file on
  1012.         the disk; this count includes any blocks that have been
  1013.         reserved for the file but do not yet have data in them,
  1014.         and any blocks that the file system uses internally to
  1015.         keep track of file data (e.g. Unix indirect blocks).
  1016.  
  1017.     short mtime
  1018.         The time of the last modification to the file, in stan-
  1019.         dard GEMDOS format.
  1020.  
  1021.     short mdate
  1022.         The date of the last modification, in standard GEMDOS
  1023.         format.
  1024.  
  1025.     short atime, adate
  1026.         The time and date of the last access to the file, in
  1027.         GEMDOS format. Filesystems that do not keep this time
  1028.         will return the values given in "mtime" and "mdate" for
  1029.         these fields as well.
  1030.  
  1031.     short ctime, cdate
  1032.         The time and date of the file's creation, in GEMDOS
  1033.         format. Filesystems that do not keep this time will
  1034.         return the values given in "mtime" and "mdate" for
  1035.         these fields as well.
  1036.  
  1037.     short attr
  1038.         The standard TOS attributes for the file, as returned
  1039.         by \#Fattrib\# and/or \#Fsfirst\#.
  1040.  
  1041.     The flag parameter controls whether or not symbolic links
  1042.     should be followed. If it is 0, then symbolic links are fol-
  1043.     lowed (like the Unix stat function). If flag is 1, then
  1044.     links are not followed and the information returned is for
  1045.     the symbolic link itself (if the named file is a symbolic
  1046.     link); this behavior is like that of the Unix lstat system
  1047.     call.
  1048.  
  1049. RETURNS
  1050.     0 on success
  1051.  
  1052.     EFILNF if the file is not found
  1053.  
  1054.     EPTHNF if the path to the file is not found.
  1055.  
  1056. SEE ALSO
  1057.     \#Fattrib\#, \#Fsnext\#
  1058.  
  1059. Last change: Oct. 1, 1991\end
  1060.  
  1061.